Conversation
Per [ST-0022](https://github.com/swiftlang/swift-evolution/blob/main/proposals/testing/0022-customtestreflectable.md), promote this interface to API.
grynspan
requested review from
briancroom,
harlanhaskins,
jerryjrchen and
stmontgomery
as code owners
grynspan
added
enhancement
|
|
||
| - ``Expectation`` | ||
| - ``ExpectationFailedError`` | ||
| - ``CustomTestStringConvertible`` |
There was a problem hiding this comment.
Are we unable to maintain this symbol reference here too? Ideally I think I'd like to be able to link to both this existing protocol and the new CustomTestReflectable from multiple places, but does DocC disallow that?
There was a problem hiding this comment.
We can but I think we're only supposed to put it under one heading?
| the description of a value _during testing only_. Values whose types conform to | ||
| this protocol use it to describe themselves when the testing library presents | ||
| them as part of the output of a test. For example, this protocol affects the | ||
| display of values you pass as arguments to test functions or that are elements |
There was a problem hiding this comment.
"elements" feels like a confusing word in this position. "…or that are sub-expressions of…" perhaps?
There was a problem hiding this comment.
Neither's a great choice but I'm not sure what exactly to put.
There was a problem hiding this comment.
"…or that are included in an expectation." sounds good to me
There was a problem hiding this comment.
That would be the passive voice.
There was a problem hiding this comment.
"…or that you include in an expectation." ?
|
|
||
| import FoodTruck | ||
|
|
||
| extension Food: CustomTestStringConvertible, CustomTestReflectable {} |
There was a problem hiding this comment.
Would these typically need @retroactive too?
There was a problem hiding this comment.
No because they'll be in the same package/project.
There was a problem hiding this comment.
Fair. Although it's not always the case that a test target is within a project which specifies a package name. For example, in Xcode projects you can specify a package identifier, but not all projects have adopted that feature. Since you have a - Note: callout at the end, consider mentioning that possibility there
There was a problem hiding this comment.
I'm not sure how to phrase it exactly. "If that doesn't work, try internal, @testable, and @retroactive" sounds a bit hammer-headed.
|
Let's plan to revisit the documentation tweaks with our DevPubs friends. |
3 participants
Per ST-0022, promote this interface to API.
Checklist: